.TH std::regex_traits::transform_primary 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::regex_traits::transform_primary \- std::regex_traits::transform_primary

.SH Synopsis
   template< class ForwardIt >
   string_type transform_primary( ForwardIt first, ForwardIt last ) const;

   For the character sequence [first, last), obtains the primary sort key in the imbued
   locale's collating order, that is, the sort key that is based on the positions of
   the letters and collation units in the national alphabet, ignoring case, diacritics,
   variants, etc. If a primary sort key compares less than another primary sort key
   with operator<, then the character sequence that produced the first sort key comes
   before the character sequence that produced the second sort key, in the currently
   imbued locale's primary collation order.

   The regex library uses this trait to match characters against equivalence classes.
   For example, the regex [[=a=]] is equivalent to the character c1 if
   traits.transform_primary(c1) is equivalent to traits.transform_primary("a") (which
   is true for any c1 from "AÀÁÂÃÄÅaàáâãäå" in the U.S. English locale). Note that
   transform_primary() takes a character sequence argument because equivalence classes
   may be multicharacter, such as [[=ch=]] in Czech or [[=dzs=]] in Hungarian.

   There is no portable way to define primary sort key in terms of std::locale since
   the conversion from the collation key returned by std::collate::transform() to the
   primary equivalence key is locale-specific, and if the user replaces the
   std::collate facet, that conversion is no longer known to the standard library's
   std::regex_traits. Standard library specializations of std::regex_traits return an
   empty string unless the std::collate facet of the currently-imbued locale was not
   replaced by the user, and still matches the system-supplied std::collate facet), in
   which case std::collate_byname<CharT>::transform(first, last) is executed and the
   sort key it produces is converted to the expected primary sort key using a
   locale-specific conversion.

.SH Parameters

   first, last - a pair of iterators which determines the sequence of characters to
                 compare
.SH Type requirements
   -
   ForwardIt must meet the requirements of LegacyForwardIterator.

.SH Return value

   The primary sort key for the character sequence [first, last) in the currently
   imbued locale, ignoring case, variant, diacritics, etc.

.SH Example

   Demonstrates the regex feature that works through transform_primary().


// Run this code

 #include <iostream>
 #include <regex>

 int main()
 {
     std::locale::global(std::locale("en_US.UTF-8"));
     std::wstring str = L"AÀÁÂÃÄÅaàáâãäå";
     std::wregex re(L"[[=a=]]*", std::regex::basic);
     std::cout << std::boolalpha << std::regex_match(str, re) << '\\n';
 }

.SH Possible output:

 true

    This section is incomplete
    Reason: could use an example with user-defined regex_traits supplying user-defined
    transform_primary

.SH Category:
     * Todo with reason
